/*
 * JavaZOOM : jlgui@javazoom.net http://www.javazoom.net
 * ----------------------------------------------------------------------- This
 * program is free software; you can redistribute it and/or modify it under the
 * terms of the GNU Library General Public License as published by the Free
 * Software Foundation; either version 2 of the License, or (at your option) any
 * later version. This program is distributed in the hope that it will be
 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
 * General Public License for more details. You should have received a copy of
 * the GNU Library General Public License along with this program; if not, write
 * to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
 * USA.----------------------------------------------------------------------
 */
package de.preamp.clients.java.player;

import java.io.IOException;
import java.io.InputStream;

import javax.sound.sampled.LineUnavailableException;
import javax.sound.sampled.UnsupportedAudioFileException;

/**
 * This interface defines player controls available. It is based on
 * javazoom.jlgui.basicplayer.BasicControler
 * 
 * @author André Stannek
 * @since 2010-08-18
 * @version 2010-08-21
 */
public interface PreampPlayerOperations
{

    /**
     * Open inputstream to play.
     * 
     * @param inputStream
     *            the InputStream to play
     * @throws IOException
     *             if an I/O exception occurs
     * @throws UnsupportedAudioFileException
     *             if the stream does not point to valid audio file data
     *             recognized by the system
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     */
    void open(InputStream inputStream) throws UnsupportedAudioFileException,
	    IOException, LineUnavailableException;

    /**
     * Skip bytes.
     * 
     * @param bytes
     *            the number of bytes to skip
     * @return bytes skipped according to audio frames constraint.
     * @throws PreampPlayerException
     *             if skipping is not supported for the playing stream
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     */
    long seek(long bytes) throws PreampPlayerException,
	    LineUnavailableException;

    /**
     * Start playback.
     * 
     * @throws PreampPlayerException
     *             if playback thread was interupted
     * @throws LineUnavailableException
     *             if a matching line is not available due to resource
     *             restrictions
     */
    void play() throws PreampPlayerException, LineUnavailableException;

    /**
     * Stop playback.
     */
    void stop();

    /**
     * Pause playback.
     */
    void pause();

    /**
     * Resume playback.
     */
    void resume();

    /**
     * Sets Pan (Balance) value. Linear scale : -1.0 <--> +1.0
     * 
     * @param pan
     *            value from -1.0 to +1.0
     * @throws PreampPlayerException
     *             if pan control is not supported
     */
    void setPan(double pan) throws PreampPlayerException;

    /**
     * Sets Gain value. Linear scale 0.0 <--> 1.0
     * 
     * @param gain
     *            value from 0.0 to 1.0
     * @throws PreampPlayerException
     *             if gain control is not supported
     */
    void setGain(double gain) throws PreampPlayerException;
}
